From 2f06ec02be1f409a1b9a01ccf8630ca1a1f2eaae Mon Sep 17 00:00:00 2001 From: =?utf8?q?Javier=20Jard=C3=B3n?= Date: Mon, 15 Nov 2010 17:20:51 +0100 Subject: [PATCH] docs: Move documentation to inline comments: gdkselection --- docs/reference/gdk/tmpl/.gitignore | 1 + docs/reference/gdk/tmpl/selections.sgml | 279 ------------------------ gdk/gdkselection.c | 75 +++++++ gdk/gdkselection.h | 109 +++++++++ 4 files changed, 185 insertions(+), 279 deletions(-) delete mode 100644 docs/reference/gdk/tmpl/selections.sgml diff --git a/docs/reference/gdk/tmpl/.gitignore b/docs/reference/gdk/tmpl/.gitignore index 4341431194..e835592bcb 100644 --- a/docs/reference/gdk/tmpl/.gitignore +++ b/docs/reference/gdk/tmpl/.gitignore @@ -12,5 +12,6 @@ keys.sgml pango_interaction.sgml pixbufs.sgml regions.sgml +selections.sgml visuals.sgml windows.sgml diff --git a/docs/reference/gdk/tmpl/selections.sgml b/docs/reference/gdk/tmpl/selections.sgml deleted file mode 100644 index 1ce9b894ab..0000000000 --- a/docs/reference/gdk/tmpl/selections.sgml +++ /dev/null @@ -1,279 +0,0 @@ - -Selections - - -Functions for transfering data via the X selection mechanism - - - -The X selection mechanism provides a way to transfer -arbitrary chunks of data between programs. -A selection is a essentially -a named clipboard, identified by a string interned -as a #GdkAtom. By claiming ownership of a selection, -an application indicates that it will be responsible -for supplying its contents. The most common -selections are PRIMARY and -CLIPBOARD. - - -The contents of a selection can be represented in -a number of formats, called targets. -Each target is identified by an atom. A list of -all possible targets supported by the selection owner -can be retrieved by requesting the special target -TARGETS. When a selection is -retrieved, the data is accompanied by a type -(an atom), and a format (an integer, representing -the number of bits per item). -See Properties and Atoms -for more information. - - -The functions in this section only contain the lowlevel -parts of the selection protocol. A considerably more -complicated implementation is needed on top of this. -GTK+ contains such an implementation in the functions -in gtkselection.h and programmers -should use those functions instead of the ones presented -here. If you plan to implement selection handling -directly on top of the functions here, you should refer -to the X Inter-client Communication Conventions Manual -(ICCCM). - - - - - - - - - - - - - - - -A #GdkAtom representing the PRIMARY selection. - - - - - - -A #GdkAtom representing the SECONDARY selection. - - - - - - -A #GdkAtom representing the CLIPBOARD selection. - - - - - - -A #GdkAtom representing the BITMAP selection target. - - - - - - -A #GdkAtom representing the COLORMAP selection target. - - - - - - -A #GdkAtom representing the DRAWABLE selection target. - - - - - - -A #GdkAtom representing the PIXMAP selection target. - - - - - - -A #GdkAtom representing the STRING selection target. - - - - - - -A #GdkAtom representing the ATOM selection type. - - - - - - -A #GdkAtom representing the BITMAP selection type. - - - - - - -A #GdkAtom representing the COLORMAP selection type. - - - - - - -A #GdkAtom representing the DRAWABLE selection type. - - - - - - -A #GdkAtom representing the INTEGER selection type. - - - - - - -A #GdkAtom representing the PIXMAP selection type. - - - - - - -A #GdkAtom representing the WINDOW selection type. - - - - - - -A #GdkAtom representing the STRING selection type. - - - - - - -Sets the owner of the given selection. - - -@owner: a #GdkWindow or %NULL to indicate that the - the owner for the given should be unset. -@selection: an atom identifying a selection. -@time_: timestamp to use when setting the selection. - If this is older than the timestamp given last - time the owner was set for the given selection, the - request will be ignored. -@send_event: if %TRUE, and the new owner is different - from the current owner, the current owner - will be sent a SelectionClear event. -@Returns: %TRUE if the selection owner was successfully - changed to @owner, otherwise %FALSE. - - - - - - - -@display: -@owner: -@selection: -@time_: -@send_event: -@Returns: - - - - -Determines the owner of the given selection. - - -@selection: an atom indentifying a selection. -@Returns: if there is a selection owner for this window, - and it is a window known to the current process, - the #GdkWindow that owns the selection, otherwise - %NULL. Note that the return value may be owned - by a different process if a foreign window - was previously created for that window, but - a new foreign window will never be created by - this call. - - - - - - - -@display: -@selection: -@Returns: - - - - -Retrieves the contents of a selection in a given -form. - - -@requestor: a #GdkWindow. -@selection: an atom identifying the selection to get the - contents of. -@target: the form in which to retrieve the selection. -@time_: the timestamp to use when retrieving the - selection. The selection owner may refuse the - request if it did not own the selection at - the time indicated by the timestamp. - - - - - - -@requestor: -@data: -@prop_type: -@prop_format: -@Returns: - - - - -Sends a response to SelectionRequest event. - - -@requestor: window to which to deliver response. -@selection: selection that was requested. -@target: target that was selected. -@property: property in which the selection owner stored the - data, or %GDK_NONE to indicate that the request - was rejected. -@time_: timestamp. - - - - - - - -@display: -@requestor: -@selection: -@target: -@property: -@time_: - - diff --git a/gdk/gdkselection.c b/gdk/gdkselection.c index eed340a02b..fc191aa74f 100644 --- a/gdk/gdkselection.c +++ b/gdk/gdkselection.c @@ -32,6 +32,54 @@ #include "gdkdisplay.h" +/** + * SECTION:selections + * @Short_description: Functions for transfering data via the X selection mechanism + * @Title: Selections + * + * The X selection mechanism provides a way to transfer arbitrary chunks of + * data between programs. A selection is a essentially + * a named clipboard, identified by a string interned as a #GdkAtom. By + * claiming ownership of a selection, an application indicates that it will + * be responsible for supplying its contents. The most common selections are + * PRIMARY and CLIPBOARD. + * + * The contents of a selection can be represented in a number of formats, + * called targets. Each target is identified by an atom. + * A list of all possible targets supported by the selection owner can be + * retrieved by requesting the special target TARGETS. When + * a selection is retrieved, the data is accompanied by a type (an atom), and + * a format (an integer, representing the number of bits per item). + * See Properties and Atoms + * for more information. + * + * The functions in this section only contain the lowlevel parts of the + * selection protocol. A considerably more complicated implementation is needed + * on top of this. GTK+ contains such an implementation in the functions in + * gtkselection.h and programmers should use those functions + * instead of the ones presented here. If you plan to implement selection + * handling directly on top of the functions here, you should refer to the + * X Inter-client Communication Conventions Manual (ICCCM). + */ + +/** + * gdk_selection_owner_set: + * @owner: a #GdkWindow or %NULL to indicate that the + * the owner for the given should be unset. + * @selection: an atom identifying a selection. + * @time_: timestamp to use when setting the selection. + * If this is older than the timestamp given last + * time the owner was set for the given selection, the + * request will be ignored. + * @send_event: if %TRUE, and the new owner is different + * from the current owner, the current owner + * will be sent a SelectionClear event. + * + * Sets the owner of the given selection. + * + * Returns: %TRUE if the selection owner was successfully + * changed to @owner, otherwise %FALSE. + */ gboolean gdk_selection_owner_set (GdkWindow *owner, GdkAtom selection, @@ -43,6 +91,21 @@ gdk_selection_owner_set (GdkWindow *owner, time, send_event); } +/** + * gdk_selection_owner_get: + * @selection: an atom indentifying a selection. + * + * Determines the owner of the given selection. + * + * Returns: if there is a selection owner for this window, + * and it is a window known to the current process, + * the #GdkWindow that owns the selection, otherwise + * %NULL. Note that the return value may be owned + * by a different process if a foreign window + * was previously created for that window, but + * a new foreign window will never be created by + * this call. + */ GdkWindow* gdk_selection_owner_get (GdkAtom selection) { @@ -50,6 +113,18 @@ gdk_selection_owner_get (GdkAtom selection) selection); } +/** + * gdk_selection_send_notify: + * @requestor: window to which to deliver response. + * @selection: selection that was requested. + * @target: target that was selected. + * @property: property in which the selection owner stored the + * data, or %GDK_NONE to indicate that the request + * was rejected. + * @time_: timestamp. + * + * Sends a response to SelectionRequest event. + */ void gdk_selection_send_notify (GdkNativeWindow requestor, GdkAtom selection, diff --git a/gdk/gdkselection.h b/gdk/gdkselection.h index fc5d4b40e8..897e0c77cf 100644 --- a/gdk/gdkselection.h +++ b/gdk/gdkselection.h @@ -38,21 +38,116 @@ G_BEGIN_DECLS /* Predefined atoms relating to selections. In general, one will need to use * gdk_intern_atom */ +/** + * GDK_SELECTION_PRIMARY: + * + * A #GdkAtom representing the PRIMARY selection. + */ #define GDK_SELECTION_PRIMARY _GDK_MAKE_ATOM (1) + +/** + * GDK_SELECTION_SECONDARY: + * + * A #GdkAtom representing the SECONDARY selection. + */ #define GDK_SELECTION_SECONDARY _GDK_MAKE_ATOM (2) + +/** + * GDK_SELECTION_CLIPBOARD: + * + * A #GdkAtom representing the CLIPBOARD selection. + */ #define GDK_SELECTION_CLIPBOARD _GDK_MAKE_ATOM (69) + +/** + * GDK_TARGET_BITMAP: + * + * A #GdkAtom representing the BITMAP selection target. + */ #define GDK_TARGET_BITMAP _GDK_MAKE_ATOM (5) + +/** + * GDK_TARGET_COLORMAP: + * + * A #GdkAtom representing the COLORMAP selection target. + */ #define GDK_TARGET_COLORMAP _GDK_MAKE_ATOM (7) + +/** + * GDK_TARGET_DRAWABLE: + * + * A #GdkAtom representing the DRAWABLE selection target. + */ #define GDK_TARGET_DRAWABLE _GDK_MAKE_ATOM (17) + +/** + * GDK_TARGET_PIXMAP: + * + * A #GdkAtom representing the PIXMAP selection target. + */ #define GDK_TARGET_PIXMAP _GDK_MAKE_ATOM (20) + +/** + * GDK_TARGET_STRING: + * + * A #GdkAtom representing the STRING selection target. + */ #define GDK_TARGET_STRING _GDK_MAKE_ATOM (31) + +/** + * GDK_SELECTION_TYPE_ATOM: + * + * A #GdkAtom representing the ATOM selection type. + */ #define GDK_SELECTION_TYPE_ATOM _GDK_MAKE_ATOM (4) + +/** + * GDK_SELECTION_TYPE_BITMAP: + * + * A #GdkAtom representing the BITMAP selection type. + */ #define GDK_SELECTION_TYPE_BITMAP _GDK_MAKE_ATOM (5) + +/** + * GDK_SELECTION_TYPE_COLORMAP: + * + * A #GdkAtom representing the COLORMAP selection type. + */ #define GDK_SELECTION_TYPE_COLORMAP _GDK_MAKE_ATOM (7) + +/** + * GDK_SELECTION_TYPE_DRAWABLE: + * + * A #GdkAtom representing the DRAWABLE selection type. + */ #define GDK_SELECTION_TYPE_DRAWABLE _GDK_MAKE_ATOM (17) + +/** + * GDK_SELECTION_TYPE_INTEGER: + * + * A #GdkAtom representing the INTEGER selection type. + */ #define GDK_SELECTION_TYPE_INTEGER _GDK_MAKE_ATOM (19) + +/** + * GDK_SELECTION_TYPE_PIXMAP: + * + * A #GdkAtom representing the PIXMAP selection type. + */ #define GDK_SELECTION_TYPE_PIXMAP _GDK_MAKE_ATOM (20) + +/** + * GDK_SELECTION_TYPE_WINDOW: + * + * A #GdkAtom representing the WINDOW selection type. + */ #define GDK_SELECTION_TYPE_WINDOW _GDK_MAKE_ATOM (33) + +/** + * GDK_SELECTION_TYPE_STRING: + * + * A #GdkAtom representing the STRING selection type. + */ #define GDK_SELECTION_TYPE_STRING _GDK_MAKE_ATOM (31) /* Selections @@ -74,6 +169,20 @@ gboolean gdk_selection_owner_set_for_display (GdkDisplay *display, GdkWindow *gdk_selection_owner_get_for_display (GdkDisplay *display, GdkAtom selection); +/** + * gdk_selection_convert: + * @requestor: a #GdkWindow. + * @selection: an atom identifying the selection to get the + * contents of. + * @target: the form in which to retrieve the selection. + * @time_: the timestamp to use when retrieving the + * selection. The selection owner may refuse the + * request if it did not own the selection at + * the time indicated by the timestamp. + * + * Retrieves the contents of a selection in a given + * form. + */ void gdk_selection_convert (GdkWindow *requestor, GdkAtom selection, GdkAtom target, -- 2.30.2